////////////////////////////////////////////////////////////////////////////////
// Copyright 2010 Michael Schmalle - Teoti Graphix, LLC
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0 
// 
// Unless required by applicable law or agreed to in writing, software 
// distributed under the License is distributed on an "AS IS" BASIS, 
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and 
// limitations under the License
// 
// Author: Michael Schmalle, Principal Architect
// mschmalle at teotigraphix dot com
////////////////////////////////////////////////////////////////////////////////

package fxplugins.utility
{

import flash.events.IEventDispatcher;

import fxplugins.core.IComponentMapAware;

/**
 * The <code>IUtilityMap</code> interface marks a class as having
 * the ability to manage the application's plugin services.
 * 
 * @author Michael Schmalle
 * @copyright Teoti Graphix, LLC
 * @productversion 1.0
 * 
 * @see fxplugins.utility.UtilityMap
 */
public interface IUtilityMap extends IEventDispatcher, IComponentMapAware
{
	//--------------------------------------------------------------------------
	//
	//  Methods
	//
	//--------------------------------------------------------------------------
	
	/**
	 * Initializes the utility map, this is to called by the mediating instance
	 * of the utility map.
	 */
	function initialize():void;
	
	/**
	 * Returns a requested utility by Class API.
	 * 
	 * @param type The Class key.
	 * @return A utility instance of the <code>Class</code> API implementation 
	 * or <code>null</code> if the type has not been registered with the plugin 
	 * utility map.
	 */
	function getUtility(type:Class):Object;
	
	/**
	 * Registers a utility against a <code>Class</code> API.
	 * 
	 * <p>If the <code>utility</code> instance is <code>null</code> and the 
	 * <code>Class</code> type is not, the old <code>utility</code> will be removed 
	 * and it's <code>dispose()</code> method will be called.</p>
	 * 
	 * @param type A <code>Class</code> type.
	 * @param utility An instance to register against the <code>Class</code> type.
	 * @return The added or removed utility instance.
	 * 
	 * @throws Error The service key cannot be null
	 * @throws Error The service is an instance of <code>type</code>
	 */
	function putUtility(type:Class, utility:Object):Object;
	
	/**
	 * Returns whether a requested utility exists for the Class API type.
	 * 
	 * @param type The Class key.
	 * @return A Boolean indicating whether the utility exists for the given
	 * <code>Class</code> API.
	 */	
	function hasUtility(type:Class):Boolean;
}
}